package org.proteusframework.platformservice;

/**
 * Describes a scoping mechanism for custom service plugin implementations, linking their instantiation to a specific
 * scope.
 */
public enum ServiceScope
{
    /**
     * A single instance of the custom service is shared across the entire scope of the application regardless of
     * who is requesting the instance.
     *
     * @see org.proteusframework.platformservice.IExtendedPlatformDelegate#getPlatformService(Class, ServiceScope)
     */
    ApplicationSingleton,

    /**
     * A single instance of the custom service is shared across all objects that share an identical family, as described
     * by {@link org.proteusframework.core.api.model.INamespace#getFamily()}.
     * <p/>
     * For example, if there are two instances of com.foo.Bar and one instance of com.foo.Baz, all three instances
     * would share a single instance of the custom platform service since all belong to the family <i>com.foo</i>.
     *
     * @see org.proteusframework.platformservice.IExtendedPlatformDelegate#getPlatformService(Class, ServiceScope, org.proteusframework.core.api.model.INamespace)
     */
    FamilySingleton,

    /**
     * A single instance of the custom service is shared across all objects that share an identical family and ID, as
     * described by {@link org.proteusframework.core.api.model.INamespace#getFamily()}.
     * <p/>
     * <b>NOTE:</b> The {@link org.proteusframework.core.api.model.INamespace#getRefId()} is not considered, and thus
     * a <code>NamespaceSingleton</code> instance is shared across multiple instances of the same object. For example,
     * if there are three instances of the com.foo.Bar class, all three instances would share a single instance
     * of the custom platform service.
     *
     * @see org.proteusframework.platformservice.IExtendedPlatformDelegate#getPlatformService(Class, ServiceScope, org.proteusframework.core.api.model.INamespace)
     */
    NamespaceSingleton,

    /**
     * A single instance of the custom service is utilized for a specific object instance, as defined by the combination
     * of {@link org.proteusframework.core.api.model.INamespace#getFamily()},
     * {@link org.proteusframework.core.api.model.INamespace#getId()}, and
     * {@link org.proteusframework.core.api.model.INamespace#getRefId()}.
     * <p/>
     * Scoping a custom service to an extended namespace provides even more granularity than scoping the instance
     * to just the namespace. The difference is subtle but important. If each instance of com.foo.Bar requires its
     * own instance of the custom service, the {@link #NamespaceSingleton} isn't adequate. Instead, when each instance
     * of com.foo.Bar is instantiated, provide a custom reference ID, thus ensuring that a finer granularity is
     * possible.
     * <p/>
     * <b>NOTE:</b> Any attempt to scope at the extended namespace level against an
     * {@link org.proteusframework.core.api.model.INamespace} that returns a <code>null</code> for its reference ID will
     * result in a {@link ServiceScopingException}.
     *
     * @see org.proteusframework.platformservice.IExtendedPlatformDelegate#getPlatformService(Class, ServiceScope, org.proteusframework.core.api.model.INamespace)
     */
    ExtendedNamespaceSingleton,

    /**
     * A new instance of the custom service is instantiated with each request.
     *
     * @see org.proteusframework.platformservice.IExtendedPlatformDelegate#getPlatformService(Class, ServiceScope)
     */
    NewInstancePerRequest
}
 
